home *** CD-ROM | disk | FTP | other *** search
/ MacWorld 2003 August / MW 8 2003 CD1.iso / Inside Macworld / Product News / gimp-1.2.4.sit / gimp-1.2.4 / devel-docs / libgimp / sgml / gimpfileselection.sgml < prev    next >
Encoding:
Text File  |  2003-05-20  |  8.8 KB  |  214 lines
  1. <refentry id="GimpFileSelection" revision="19 Jan 2001">
  2. <refmeta>
  3. <refentrytitle>GimpFileSelection</refentrytitle>
  4. <manvolnum>3</manvolnum>
  5. <refmiscinfo>LIBGIMP Library</refmiscinfo>
  6. </refmeta>
  7.  
  8. <refnamediv>
  9. <refname>GimpFileSelection</refname><refpurpose>Widget for entering a filename.</refpurpose>
  10. </refnamediv>
  11.  
  12. <refsynopsisdiv><title>Synopsis</title>
  13. <synopsis>
  14.  
  15.  
  16.  
  17. struct      <link linkend="GimpFileSelection-struct">GimpFileSelection</link>;
  18. #define     <link linkend="GIMP-FILE-SELECTION-CAPS">GIMP_FILE_SELECTION</link>             (obj)
  19. <link linkend="GtkWidget">GtkWidget</link>*  <link linkend="gimp-file-selection-new">gimp_file_selection_new</link>         (const <link linkend="gchar">gchar</link> *title,
  20.                                              const <link linkend="gchar">gchar</link> *filename,
  21.                                              <link linkend="gboolean">gboolean</link> dir_only,
  22.                                              <link linkend="gboolean">gboolean</link> check_valid);
  23. <link linkend="gchar">gchar</link>*      <link linkend="gimp-file-selection-get-filename">gimp_file_selection_get_filename</link>
  24.                                             (<link linkend="GimpFileSelection">GimpFileSelection</link> *gfs);
  25. void        <link linkend="gimp-file-selection-set-filename">gimp_file_selection_set_filename</link>
  26.                                             (<link linkend="GimpFileSelection">GimpFileSelection</link> *gfs,
  27.                                              const <link linkend="gchar">gchar</link> *filename);
  28.  
  29. </synopsis>
  30. </refsynopsisdiv>
  31.  
  32. <refsect1>
  33. <title>Object Hierarchy</title>
  34. <synopsis>
  35.  
  36.   <link linkend="GtkObject">GtkObject</link>
  37.    +----<link linkend="GtkWidget">GtkWidget</link>
  38.          +----<link linkend="GtkContainer">GtkContainer</link>
  39.                +----<link linkend="GtkBox">GtkBox</link>
  40.                      +----<link linkend="GtkHBox">GtkHBox</link>
  41.                            +----GimpFileSelection
  42. </synopsis>
  43.  
  44. </refsect1>
  45.  
  46.  
  47. <refsect1>
  48. <title>Signal Prototypes</title>
  49. <synopsis>
  50.  
  51. "<link linkend="GimpFileSelection-filename-changed">filename-changed</link>"
  52.             void        user_function      (<link linkend="GimpFileSelection">GimpFileSelection</link> *gimpfileselection,
  53.                                             <link linkend="gpointer">gpointer</link> user_data);
  54. </synopsis>
  55. </refsect1>
  56.  
  57.  
  58. <refsect1>
  59. <title>Description</title>
  60. <para>
  61. This widget is used to enter filenames or directories.
  62. </para>
  63. <para>
  64. There is a <link linkend="GtkEntry">GtkEntry</link> for entering the filename manually and a "..."
  65. button which will pop up a <link linkend="GtkFileSelection">GtkFileSelection</link> dialog.
  66. </para>
  67. <para>
  68. You can restrict the <link linkend="GimpFileSelection">GimpFileSelection</link> to directories. In this case
  69. the filename listbox of the <link linkend="GtkFileSelection">GtkFileSelection</link> dialog will be hidden.
  70. </para>
  71. <para>
  72. If you specify <parameter>check_valid</parameter> as <link linkend="TRUE-CAPS">TRUE</link> in <link linkend="gimp-file-selection-new">gimp_file_selection_new</link>()
  73. the entered filename will be checked for validity and a pixmap will be
  74. shown which indicates if the file exists or not.
  75. </para>
  76. <para>
  77. Whenever the user changes the filename, the "filename_changed" signal
  78. will be emitted.
  79. </para>
  80. </refsect1>
  81.  
  82. <refsect1>
  83. <title>Details</title>
  84. <refsect2>
  85. <title><anchor id="GimpFileSelection-struct">struct GimpFileSelection</title>
  86. <programlisting>struct GimpFileSelection;</programlisting>
  87. <para>
  88.  
  89. </para></refsect2>
  90. <refsect2>
  91. <title><anchor id="GIMP-FILE-SELECTION-CAPS">GIMP_FILE_SELECTION()</title>
  92. <programlisting>#define GIMP_FILE_SELECTION(obj)            (GTK_CHECK_CAST ((obj), GIMP_TYPE_FILE_SELECTION, GimpFileSelection))
  93. </programlisting>
  94. <para>
  95. Checks if the passed pointer is a pointer to a <link linkend="GimpFileSelection">GimpFileSelection</link> and
  96. performs the cast if valid.
  97. </para><informaltable pgwide=1 frame="none" role="params">
  98. <tgroup cols="2">
  99. <colspec colwidth="2*">
  100. <colspec colwidth="8*">
  101. <tbody>
  102. <row><entry align="right"><parameter>obj</parameter> :</entry>
  103. <entry>The pointer to cast.
  104.  
  105.  
  106. </entry></row>
  107. </tbody></tgroup></informaltable></refsect2>
  108. <refsect2>
  109. <title><anchor id="gimp-file-selection-new">gimp_file_selection_new ()</title>
  110. <programlisting><link linkend="GtkWidget">GtkWidget</link>*  gimp_file_selection_new         (const <link linkend="gchar">gchar</link> *title,
  111.                                              const <link linkend="gchar">gchar</link> *filename,
  112.                                              <link linkend="gboolean">gboolean</link> dir_only,
  113.                                              <link linkend="gboolean">gboolean</link> check_valid);</programlisting>
  114. <para>
  115. Creates a new <link linkend="GimpFileSelection">GimpFileSelection</link> widget.</para>
  116. <para>
  117.  
  118. </para><informaltable pgwide=1 frame="none" role="params">
  119. <tgroup cols="2">
  120. <colspec colwidth="2*">
  121. <colspec colwidth="8*">
  122. <tbody>
  123. <row><entry align="right"><parameter>title</parameter> :</entry>
  124. <entry> The title of the <link linkend="GtkFileSelection">GtkFileSelection</link> dialog.
  125. </entry></row>
  126. <row><entry align="right"><parameter>filename</parameter> :</entry>
  127. <entry> The initial filename.
  128. </entry></row>
  129. <row><entry align="right"><parameter>dir_only</parameter> :</entry>
  130. <entry> <link linkend="TRUE-CAPS">TRUE</link> if the file selection should accept directories only.
  131. </entry></row>
  132. <row><entry align="right"><parameter>check_valid</parameter> :</entry>
  133. <entry> <link linkend="TRUE-CAPS">TRUE</link> if the widget should check if the entered file
  134. really exists.
  135. </entry></row>
  136. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> A pointer to the new <link linkend="GimpFileSelection">GimpFileSelection</link> widget.
  137. </entry></row>
  138. </tbody></tgroup></informaltable></refsect2>
  139. <refsect2>
  140. <title><anchor id="gimp-file-selection-get-filename">gimp_file_selection_get_filename ()</title>
  141. <programlisting><link linkend="gchar">gchar</link>*      gimp_file_selection_get_filename
  142.                                             (<link linkend="GimpFileSelection">GimpFileSelection</link> *gfs);</programlisting>
  143. <para>
  144. Note that you have to <link linkend="g-free">g_free</link>() the returned string.</para>
  145. <para>
  146.  
  147. </para><informaltable pgwide=1 frame="none" role="params">
  148. <tgroup cols="2">
  149. <colspec colwidth="2*">
  150. <colspec colwidth="8*">
  151. <tbody>
  152. <row><entry align="right"><parameter>gfs</parameter> :</entry>
  153. <entry> The file selection you want to know the filename from.
  154. </entry></row>
  155. <row><entry align="right"><emphasis>Returns</emphasis> :</entry><entry> The file or directory the user has entered.
  156. </entry></row>
  157. </tbody></tgroup></informaltable></refsect2>
  158. <refsect2>
  159. <title><anchor id="gimp-file-selection-set-filename">gimp_file_selection_set_filename ()</title>
  160. <programlisting>void        gimp_file_selection_set_filename
  161.                                             (<link linkend="GimpFileSelection">GimpFileSelection</link> *gfs,
  162.                                              const <link linkend="gchar">gchar</link> *filename);</programlisting>
  163. <para>
  164. If you specified <parameter>check_valid</parameter> as <link linkend="TRUE-CAPS">TRUE</link> in <link linkend="gimp-file-selection-new">gimp_file_selection_new</link>()
  165. the <link linkend="GimpFileSelection">GimpFileSelection</link> will immediately check the validity of the file
  166. name.</para>
  167. <para>
  168.  
  169. </para><informaltable pgwide=1 frame="none" role="params">
  170. <tgroup cols="2">
  171. <colspec colwidth="2*">
  172. <colspec colwidth="8*">
  173. <tbody>
  174. <row><entry align="right"><parameter>gfs</parameter> :</entry>
  175. <entry> The file selection you want to set the filename for.
  176. </entry></row>
  177. <row><entry align="right"><parameter>filename</parameter> :</entry>
  178. <entry> The new filename.
  179. </entry></row>
  180. </tbody></tgroup></informaltable></refsect2>
  181.  
  182. </refsect1>
  183.  
  184. <refsect1>
  185. <title>Signals</title>
  186. <refsect2><title><anchor id="GimpFileSelection-filename-changed">The "filename-changed" signal</title>
  187. <programlisting>void        user_function                  (<link linkend="GimpFileSelection">GimpFileSelection</link> *gimpfileselection,
  188.                                             <link linkend="gpointer">gpointer</link> user_data);</programlisting>
  189. <para>
  190. This signal is emitted whenever the user changes the filename.
  191. </para><informaltable pgwide=1 frame="none" role="params">
  192. <tgroup cols="2">
  193. <colspec colwidth="2*">
  194. <colspec colwidth="8*">
  195. <tbody>
  196. <row><entry align="right"><parameter>gimpfileselection</parameter> :</entry>
  197. <entry>the object which received the signal.
  198.  
  199. </entry></row>
  200. <row><entry align="right"><parameter>user_data</parameter> :</entry>
  201. <entry>user data set when the signal handler was connected.</entry></row>
  202. </tbody></tgroup></informaltable></refsect2>
  203. </refsect1>
  204.  
  205.  
  206. <refsect1>
  207. <title>See Also</title>
  208. <para>
  209. <link linkend="GimpPathEditor">GimpPathEditor</link>
  210. </para>
  211. </refsect1>
  212.  
  213. </refentry>
  214.